VBThread is an ActiveX DLL which allows Visual Basic 5.0 applications to create real threads just like other languages such as C or Java. The DLL does not require any DLLs other than the ones you normally distribute with your application.
This is the component reference for VBThread, distributed with VBThread as an ASCII file.
Installation Instruction
========================
After downloading the zipped archive, extract it using zip extractor which support long file names such as WinZip for Windows. You should get this files:
Demo files:
- multiThread.vbp (Visual Basic 5 project file)
- frmMultiThread.frm (Visual Basic 5 form)
- modMultiThread.bas (Visual Basic 5 module)
- docs.txt (this file)
VBThread files:
- VBthread.dll (VBThread ActiveX DLL)
Copy Demo files to a single directory. To try the application, you MUST compile it to exe file first, and execute that exe file. If you try it from within VB5 IDE, you will get system error since VB5 IDE doesn't support multithreading process.
Copy VBthread.dll to your windows\system\ directory, and register it using regsvr32 by typing this command at command prompt:
c:\windows\system\regsvr32 VBThread.dll
you will get confirmation on succesfull registration.
Project Demonstrations
======================
You will probably want to dive right in. VBThread demonstration projects is included to make you understand how it works immediately and easily. We suggest you start there! Not only will this be a good test to make sure the ActiveX DLL was installed properly, but you will get to see VBThread in operation almost immediately. Remember, you must have Microsoft Visual Basic 5.0 installed prior to using VBThread.
NOTE:
Make sure these projects configured with "VBThread 1.0" specified under Project | References.
The first thing you should do after loading a demonstration project is to check "VBThread 1.0" from the Project | References menu.
MultiThread Demo Project
========================
After starting MultiThread, a thread viewer window appears on your desktop. This application demonstrates how to use and control three separate threads. All threads are initially unloaded. Use the "Load" buttons to load threads and "Start" and see what happens! If you are using the demo version of VBThread, you will also see the splash screen appear about five seconds and then disappear.
The thread viewer shows the status of the three separate threads. All are executing their own thread functions which update the viewer with current loop iteration. Each thread is programmed to update the viewer each iteration, and display other thread's status, other has run. You can interactively change thread's priority by selecting from combo box and see immediately how it affect thread's execution. Feel free to browse the source code and see how it is all done.
Using VBThread
==============
To use VBThread in your own project, follow these simple steps:
Add VBThread to Your Project
Open your project.
Select "References" from the "Project" pull-down menu.
Find and select "VBThread 1.0".
If you could not find it, make sure you selected "References" not "Components.". If you did, re-register VBThread.dll.
Click OK.
Using VBThread in Your Project
Create a Visual Basic subroutine (i.e. "MyThreadSub(ByVal lParam As Long)") which contains the code you wish the thread to execute.
The Sub must be public in a basic module, not a Form or a class module. You can optionally include the lParam parameter. If you do include it, you must specify the ByVal keyword so that VBThread can pass the long integer by value.
Create a ThreadVB object (i.e. "myThread") in a basic module (usually a global declare in your Declarations section.) Note: Creating an object creates a unique VBThread object. You can create as many as you like. If you want to get VBThread's events, add WithEvents keyword to your declaration.
Option Explicit
Global myThread As New ThreadVB
In your startup object (Sub Main() or Form_Load()), add code to create the thread. You'll need to tell VBThread which Visual Basic Sub to use for the thread using the AddressOf operator. For more information on AddressOf, see Visual Basic Help. The second parameter, lParam, is used to pass a long integer value into the thread sub. If you have no need for lParam, just leave it.
myThread.LoadFunction AddressOf MyThreadSub
At this point in your code's execution, a VBThread object has been created in your project. It is suspended (until you tell it to resume), so it has done nothing more than increment the thread count for your application. To view the thread count for any application, use NT's Task Manager. From the Task Manager, be sure to select "Select Columns..." from the "View" pull-down menu, then select "Thread Count."
Depending on the urgency of the thread, or how much CPU resources you suspect it might consume, you may wish to set the priority for the thread to be lower than normal. We recommend you set all threads to the lowest setting possible, VBThreadLowest, or -2. There are other settings as well. Please refer to the "Priority" property below.
myThread.fnPriority = VBThreadLowest
The thread is now ready to go! Since it was loaded in a suspended state by calling the LoadFunction method, you have to "start" the thread in order for it to begin execution. Throughout the life of threads, you may manually suspend a thread (StopFunction) or resume it (StartFunction) from anywhere in your project.
To start your newly loaded and suspended thread, call the StartFunction method:
myThread.StartFunction
The thread function you specified after the AddressOf operator (MyThreadSub) in LoadFunction is now running. When your Sub, MyThreadSub, is complete, the thread will still exist, but will be suspended. That is why it is good practice for the thread to terminate itself. It is a good idea to put this code as the last line of your Sub.
myThread.UnloadFunction
There is one last thing you should do within your project. In your Unload event (or closing routine), make sure that all of the threads that you created have exited, or are at least suspended. It is best to exit a thread before exiting your application, but at worst case, make sure the thread is at least stopped. If you try to close your application when threads are still running, your application will crash.
To use the StopFunction method, see the following example:
myThread.StopFunction
Properly Exiting a Thread
The best way to handle an executing thread, however, is to tell it to exit via UnloadFunction:
myThread.UnloadFunction
Troubleshooting Notes
=====================
Here are some notes to guide you when using VBThread:
Always exit your threads properly before shutting down your application. At best, remember to stop your threads before shutting down. You can do this by using the UnloadFunction methods for each thread in your project's Unload event.
Visual Basic 5.0's design environment is not thread safe, so testing and debugging of your threads is impossible. Test your threads individually, first, in other non-thread subroutines before turning them into threads.
Test your threads by running your executable, not by running your project in design mode. You are almost assured crashes if attempted.
When dealing with threads, be sure to save your code often.
Optimize your threads! Use the fnPriority property to set the priority for each thread you create.
Properties
==========
Each property of the VBThread class is described, below.
fnAddress(Long)
Return Function/Sub address on which the thread is calling. You can pass this property to another Win32API function that required the handle.
Read-Only at run-time
fnParam(Long)
Returns the parameters you pass to the thread.
Read-Only at runtime.
fnStarted(Boolean)
Returns the execution status of the thread.
Read-Only at runtime.
To determine the whether or not a thread has started, access this read-only property. If true, the thread is still executing.
fnLoaded(Boolean)
Returns the availability of the thread.
Read-Only at runtime.
To determine the whether or not a thread has loaded, access this read-only property. If true, the thread is properly loaded.
hdlThread(Long)
Return thread's handle. You can pass this property to another Win32API function that required the handle.
Read-Only at run-time
ThreadID(Long)
Return thread's ID. You can pass this property to another Win32API function that required the handle.
Read-Only at run-time
Tag(String)
Stores any extra data needed for your thread. Like most Visual Basic controls, a Tag property is available for each VBThread object. Using this tag, you can store virtually any kind of data such as a counter.
Read/Write at runtime.
Default: Zero-length string
fnPriority(ThreadPriority)
Return thread's priority. You can change this property only if you have succesfully load your function with LoadFunction method. Changing fnPriority before it has not effect.
Read-Write at run-time
Possible values:
VBThreadLowest = -2
VBThreadBelowNormal = -1
VBThreadNormal = 0
VBThreadAboveNormal = 1
VBThreadHighest = 2
VBThreadIdle = -15
VBThreadTimeCritical = 15
For most threads, we recommend the lowest setting (-2), however if you need your thread to be processed immediately, you may choose a higher setting. Check your application's CPU utilization and adjust as needed.
Like most Visual Basic controls, a Tag property is available for each VBThread object. Using this tag, you can store virtually any kind of data such as a counter.
Methods
=======
Each method of the VBThread class is described, below.
LoadFunction(ptrStartRoutine As Long, Optional ByVal lParam As Long=0)
Creates a new suspended thread.
Parameters:
ptrStartRoutine as Long
The address of the Visual Basic subroutine. LoadFunction uses this address to reference your Sub for use by the thread. Use the AddressOf operator in your code to pass the address to LoadFunction.
lParam As Long
A long integer value to pass to the thread sub. It is optional,
UnloadFunction()
Exits a executing thread.
Parameters: (None)
StartFunction()
Start a suspended thread.
Parameters: (None)
StartFunction will resume (start) a suspended (paused) thread. This method is typically used soon after creating the thread via LoadFunction.
Notes:
Each thread keeps track of a "suspend count." Calling StopFunction increments this count, so if several different pieces of your code suspend the thread, the count will rise. StartFunction looks at this count and if the count is greater than 0, it decrements the count. If the new count equals zero, it resumes the thread as expected. This counter ensures that multiple suspend requests are handled properly. It also means that your calls to StopFunction and StartFunction must match.
StopFunction()
Suspends an executing thread.
Parameters: (None)
The opposite of StartFunction, StopFunction suspends an executing thread, essentially putting it to sleep.
Notes:
Each thread keeps track of a "suspend count." Calling StopFunction increments this count, so if several different pieces of your code suspend the thread, the count will rise. StartFunction looks at this count and if the count is greater than 0, it decrements the count. If the new count equals zero, it resumes the thread as expected. This counter ensures that multiple suspend requests are handled properly. It also means that your calls to StopFunction and StartFunction must match.
Events
======
This is what VBThread superior from it's competitor, by having thread's events, you can easily track thread's status/activity and get event's parameters.
Each event of the VBThread class is described, below.
FunctionLoaded(lpThreadID As Long)
Raised when you loading your function with LoadFunction, lpThreadID is the ID for the thread.
FunctionStarted(dwPausedCount As Long)
Raised when you start your function with StartFunction, dwPausedCount is the counter for the suspended thread.
FunctionPaused(dwPausedCount As Long)
Raised when you stop your function with StopFunction, dwPausedCount is the counter for the suspended thread.
FunctionUnloaded(dwExitStatus As Long)
Raised when you unload your function with UnloadFunction, dwExitStatus is the status code for the thread.
Distribution
============
The only file you need to distribute with your application is the VBThread ActiveX DLL (VBThread.DLL). Since VBThread was developed in Visual Basic 5.0, it requires the standard VB5 libraries distributed with your application.
When installing VBThread.DLL, be sure to install it into the user's SYSTEM folder for Windows 95 or SYSTEM32 folder for Windows NT. Also, be sure to register VBThread since it is, after all, an ActiveX DLL. Your installation software should provide this capability. If not, install REGSVR32.EXE with your other files and execute "REGSVR32.EXE <path>VBThread.dll" to register it properly.
Required Files
File Install To Self-Register
VBThread.DLL \SYSTEM32 (NT) or \SYSTEM (Win95) Yes
MSVBVM50.DLL \SYSTEM32 (NT) or \SYSTEM (Win95) Yes
Support
Technical support is available only by email. No telephone support is available for this product and source code is not available.
